Help/UGens/Synth control/NamedControl.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <meta http-equiv="Content-Style-Type" content="text/css">
   6 <title></title>
   7 <meta name="Generator" content="Cocoa HTML Writer">
   8 <meta name="CocoaVersion" content="949.43">
   9 <style type="text/css">
  10 p.p1 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica}
  11 p.p2 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica; min-height: 14.0px}
  12 p.p3 {margin: 0.0px 0.0px 0.0px 0.0px; font: 14.0px Helvetica}
  13 p.p4 {margin: 0.0px 0.0px 0.0px 0.0px; font: 14.0px Helvetica; min-height: 17.0px}
  14 p.p5 {margin: 0.0px 0.0px 0.0px 57.0px; text-indent: -57.0px; font: 12.0px Helvetica}
  15 p.p6 {margin: 0.0px 0.0px 0.0px 57.0px; text-indent: -57.0px; font: 12.0px Helvetica; min-height: 14.0px}
  16 p.p7 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; min-height: 12.0px}
  17 p.p8 {margin: 0.0px 0.0px 0.0px 57.0px; text-indent: -57.0px; font: 14.0px Helvetica}
  18 p.p9 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #bf0000}
  19 p.p10 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #000000; min-height: 12.0px}
  20 p.p11 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #000000}
  21 p.p12 {margin: 0.0px 0.0px 0.0px 57.0px; text-indent: -57.0px; font: 14.0px Helvetica; min-height: 17.0px}
  22 p.p13 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco}
  23 span.s1 {font: 18.0px Helvetica}
  24 span.s2 {color: #0000ff}
  25 span.s3 {color: #0000bf}
  26 span.s4 {color: #007300}
  27 span.s5 {color: #000000}
  28 span.Apple-tab-span {white-space:pre}
  29 </style>
  30 </head>
  31 <body>
  32 <p class="p1"><span class="s1"><b>NamedControl</b></span><span class="Apple-tab-span">  </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><b>named reference to a control</b></p>
  33 <p class="p2"><br></p>
  34 <p class="p1"><b>Inherits from: </b><a href="../../Core/Object.html"><span class="s2">Object</span></a></p>
  35 <p class="p2"><br></p>
  36 <p class="p1">A NamedControl directly combines a <a href="ControlName.html"><span class="s2">ControlName</span></a> and a <a href="Control.html"><span class="s2">Control</span></a> UGen conveniently. Also this makes it safe even if several identical controls exist (see example below).</p>
  37 <p class="p2"><br></p>
  38 <p class="p1">There are syntax shortcuts that generate NamedControls from the name:</p>
  39 <p class="p2"><br></p>
  40 <p class="p1"><span class="Apple-tab-span">     </span>\name.ar(values, lags)</p>
  41 <p class="p1"><span class="Apple-tab-span">     </span>\name.kr(values, lags, fixedLag)</p>
  42 <p class="p1"><span class="Apple-tab-span">     </span>\name.ir(values, lags)</p>
  43 <p class="p1"><span class="Apple-tab-span">     </span>\name.tr(values, lags)</p>
  44 <p class="p2"><br></p>
  45 <p class="p3"><b>Class Methods</b></p>
  46 <p class="p4"><b></b><br></p>
  47 <p class="p5"><b>*ar(name, values, lags)</b></p>
  48 <p class="p5"><b><span class="Apple-tab-span">  </span><span class="Apple-tab-span">    </span></b>add a new instance of AudioControl with given <b>name</b> and default <b>values</b>.<span class="Apple-converted-space"> </span></p>
  49 <p class="p5"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span>If <b>lags</b> are given, apply a <a href="../Filters/Lag.html"><span class="s2">Lag</span></a> UGen to it.</p>
  50 <p class="p5"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span><b>\symbol.ar(values, lags)</b> is a synonym.</p>
  51 <p class="p2"><br></p>
  52 <p class="p5"><b>*kr(name, values, lags, fixedLag)</b></p>
  53 <p class="p5"><b><span class="Apple-tab-span">  </span><span class="Apple-tab-span">    </span></b>add a new instance of <a href="Control.html"><span class="s2">Control</span></a> (kr) with given <b>name</b> and default <b>values</b>.<span class="Apple-converted-space"> </span></p>
  54 <p class="p5"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span>If <b>lags</b> are given, apply a <a href="../Filters/Lag.html"><span class="s2">Lag</span></a> UGen to it. If <b>fixedLag</b> is set to true, create a LagControl<span class="Apple-converted-space"> </span></p>
  55 <p class="p5"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span>(lags cannot be modulated then, but fewer UGens are required).</p>
  56 <p class="p5"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span><b>\symbol.kr(values, lags, fixedLag)</b> is a synonym.</p>
  57 <p class="p6"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span></p>
  58 <p class="p5"><b>*ir(name, values, lags)</b></p>
  59 <p class="p5"><b><span class="Apple-tab-span">  </span><span class="Apple-tab-span">    </span></b>add a new instance of <a href="Control.html"><span class="s2">Control</span></a> (ir) with given <b>name</b> and default <b>values</b>.<span class="Apple-converted-space"> </span></p>
  60 <p class="p5"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span>If <b>lags</b> are given, apply a <a href="../Filters/Lag.html"><span class="s2">Lag</span></a> UGen to it.</p>
  61 <p class="p5"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span><b>\symbol.ir(values, lags)</b> is a synonym.</p>
  62 <p class="p2"><br></p>
  63 <p class="p5"><b>*tr(name, values, lags)</b></p>
  64 <p class="p5"><b><span class="Apple-tab-span">  </span><span class="Apple-tab-span">    </span></b>add a new instance of TrigControl with given <b>name</b> and default <b>values</b>.<span class="Apple-converted-space"> </span></p>
  65 <p class="p5"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span>If <b>lags</b> are given, apply a <a href="../Filters/Lag.html"><span class="s2">Lag</span></a> UGen to it.</p>
  66 <p class="p5"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span><b>\symbol.tr(values, lags)</b> is a synonym.</p>
  67 <p class="p6"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span></p>
  68 <p class="p5"><b>*new(name, values, rate, lags, fixedLag)</b></p>
  69 <p class="p5"><b><span class="Apple-tab-span">  </span><span class="Apple-tab-span">    </span></b>add a new instance with the given <b>rate</b>, <b>name</b> and default <b>values</b>.</p>
  70 <p class="p5"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span>If <b>lags</b> are given, apply a <a href="../Filters/Lag.html"><span class="s2">Lag</span></a> UGen to it. If <b>fixedLag</b> is set to true, create a LagControl<span class="Apple-converted-space"> </span></p>
  71 <p class="p5"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span>(lags cannot be modulated then, but fewer UGens are required).</p>
  72 <p class="p6"><br></p>
  73 <p class="p2"><br></p>
  74 <p class="p7"><br></p>
  75 <p class="p8"><b>Examples</b></p>
  76 <p class="p7"><br></p>
  77 <p class="p7"><br></p>
  78 <p class="p9">// use NamedControl to create a number of multichannel controls:</p>
  79 <p class="p10"><br></p>
  80 <p class="p11">a = { <span class="s3">SinOsc</span>.ar(<span class="s3">NamedControl</span>.kr(<span class="s4">\freq</span>, [300, 330, 370], [1, 0.3, 0.02])).sum * 0.1 }.play;</p>
  81 <p class="p11">a.setn(<span class="s4">\freq</span>, [700, 705, 890]);</p>
  82 <p class="p11">a.setn(<span class="s4">\freq</span>, [0, 2, 5].midiratio * 400);</p>
  83 <p class="p10"><br></p>
  84 <p class="p9">// synonymous:</p>
  85 <p class="p11">a = { <span class="s3">SinOsc</span>.ar(<span class="s4">\freq</span>.kr([300, 330, 370], [1, 0.3, 0.02])).sum * 0.1 }.play;</p>
  86 <p class="p10"><br></p>
  87 <p class="p9">// multiple usage of the same name:</p>
  88 <p class="p11">a = { <span class="s3">SinOsc</span>.ar(<span class="s4">\freq</span>.kr(440, 3.5)) + <span class="s3">Saw</span>.ar(<span class="s4">\freq</span>.kr(440, 0.05) * 0.5) * 0.1 }.play;</p>
  89 <p class="p10"><br></p>
  90 <p class="p10"><br></p>
  91 <p class="p11">a.set(<span class="s4">\freq</span>, 1220)</p>
  92 <p class="p11">a.set(<span class="s4">\freq</span>, 120)</p>
  93 <p class="p10"><br></p>
  94 <p class="p12"><b></b><br></p>
  95 <p class="p8"><b>Comparison with direct use of Controls:</b></p>
  96 <p class="p7"><br></p>
  97 <p class="p13">In the situation when functions are used to combine UGens to more complex SynthDefs, it may not be known which ControlNames are already taken by others. NamedControl allows to reuse existing control names.<span class="Apple-converted-space"> </span></p>
  98 <p class="p7"><br></p>
  99 <p class="p9">// compare:</p>
 100 <p class="p11">(</p>
 101 <p class="p11">a = {</p>
 102 <p class="p11"><span class="Apple-tab-span">    </span><span class="s3">var</span> x, y;</p>
 103 <p class="p11"><span class="Apple-tab-span">    </span>x = <span class="s3">NamedControl</span>.kr(<span class="s4">\freq</span>, 440, 3.5);</p>
 104 <p class="p11"><span class="Apple-tab-span">    </span>y = <span class="s3">NamedControl</span>.kr(<span class="s4">\freq</span>, 440, 1);</p>
 105 <p class="p11"><span class="Apple-tab-span">    </span><span class="s3">SinOsc</span>.ar([x, y] * [2, 1.2]) * 0.1</p>
 106 <p class="p11">}.play;</p>
 107 <p class="p11">)</p>
 108 <p class="p10"><br></p>
 109 <p class="p11">a.set(<span class="s4">\freq</span>, 1220)</p>
 110 <p class="p11">a.set(<span class="s4">\freq</span>, 120)</p>
 111 <p class="p10"><br></p>
 112 <p class="p11">(</p>
 113 <p class="p11">a = {</p>
 114 <p class="p11"><span class="Apple-tab-span">    </span><span class="s3">var</span> x, y;</p>
 115 <p class="p11"><span class="Apple-tab-span">    </span>x = <span class="s3">Control</span>.names([<span class="s4">\freq</span>]).kr(440).lag(3.5);</p>
 116 <p class="p11"><span class="Apple-tab-span">    </span>y = <span class="s3">Control</span>.names([<span class="s4">\freq</span>]).kr(440).lag(1);</p>
 117 <p class="p11"><span class="Apple-tab-span">    </span><span class="s3">SinOsc</span>.ar([x, y] * [2, 1.2]) * 0.1</p>
 118 <p class="p11">}.play;</p>
 119 <p class="p11">)</p>
 120 <p class="p10"><br></p>
 121 <p class="p11">a.set(<span class="s4">\freq</span>, 1220)</p>
 122 <p class="p11">a.set(<span class="s4">\freq</span>, 120)</p>
 123 <p class="p10"><br></p>
 124 <p class="p10"><br></p>
 125 <p class="p10"><br></p>
 126 <p class="p9">// Here is a basic example using a dictionary<span class="Apple-converted-space"> </span></p>
 127 <p class="p9">// with functions that can be combined to build SynthDefs.</p>
 128 <p class="p7"><br></p>
 129 <p class="p13">(</p>
 130 <p class="p11">q = ();</p>
 131 <p class="p11">q.makeEnv = { <span class="s3">|q, env, doneAction = 0|</span> <span class="s3">EnvGen</span>.kr(env, <span class="s3">NamedControl</span>.kr(<span class="s4">\gate</span>, 1), doneAction: doneAction) };</p>
 132 <p class="p11">q.chooseNoise = { [ {<span class="s3">PinkNoise</span>.ar}, {<span class="s3">WhiteNoise</span>.ar}, {<span class="s3">LFNoise2</span>.ar(<span class="s3">Rand</span>(100, 1000))}].choose.value};</p>
 133 <p class="p11">q.filterInput = { <span class="s3">|q, in|</span> [<span class="Apple-converted-space"> </span></p>
 134 <p class="p11"><span class="Apple-tab-span">    </span>{ <span class="s3">BPF</span>.ar(in * 15, <span class="s3">NamedControl</span>.kr(<span class="s4">\freq</span>, 800), 0.2) },<span class="Apple-converted-space"> </span></p>
 135 <p class="p11"><span class="Apple-tab-span">    </span>{ R<span class="s3">HPF</span>.ar(in, <span class="s3">NamedControl</span>.kr(<span class="s4">\freq</span>, 800, 0.2)<span class="s5">, 0.2</span>) }</p>
 136 <p class="p11"><span class="Apple-tab-span">    </span>].choose.value</p>
 137 <p class="p11">};</p>
 138 <p class="p13">)</p>
 139 <p class="p7"><br></p>
 140 <p class="p9">// test the envelope:</p>
 141 <p class="p11">a = { <span class="s3">SinOsc</span>.ar(440) * q.makeEnv(<span class="s3">Env</span>.asr, 2) * 0.1 }.play;</p>
 142 <p class="p9"><span class="s5">a.set(</span><span class="s4">\gate</span><span class="s5">, -3); </span>// release in 3 seconds</p>
 143 <p class="p7"><br></p>
 144 <p class="p9">// single channel:</p>
 145 <p class="p11">a = { q.chooseNoise * q.makeEnv(<span class="s3">Env</span><span class="s5">.asr, 2</span>) }.play;</p>
 146 <p class="p9"><span class="s5">a.set(</span><span class="s4">\gate</span><span class="s5">, -3); </span>// release in 3 seconds</p>
 147 <p class="p7"><br></p>
 148 <p class="p13">a = { q.filterInput(q.chooseNoise) * q.makeEnv(Env.asr, 2) }.play;</p>
 149 <p class="p9"><span class="s5">a.set(</span><span class="s4">\freq</span><span class="s5">, 1000); </span>// set filter frequency</p>
 150 <p class="p9"><span class="s5">a.set(</span><span class="s4">\gate</span><span class="s5">, -3); </span>// release in 3 seconds</p>
 151 <p class="p7"><br></p>
 152 <p class="p13">(</p>
 153 <p class="p11">a = {</p>
 154 <p class="p11"><span class="Apple-tab-span">    </span><span class="s3">var</span> channels = <span class="s3">Array</span>.fill(8, {</p>
 155 <p class="p11"><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span>q.filterInput(q.chooseNoise) * <span class="s5">q.makeEnv(</span><span class="s3">Env</span><span class="s5">.asr, 2)</span></p>
 156 <p class="p11"><span class="Apple-tab-span">    </span>});</p>
 157 <p class="p11"><span class="Apple-tab-span">    </span><span class="s3">Splay</span>.ar(channels);</p>
 158 <p class="p10"><br></p>
 159 <p class="p11">}.play;</p>
 160 <p class="p13">)</p>
 161 <p class="p9"><span class="s5">a.set(</span><span class="s4">\freq</span><span class="s5">, 6000); </span>// set filter frequency</p>
 162 <p class="p9"><span class="s5">a.set(</span><span class="s4">\gate</span><span class="s5">, -3); </span>// release in 3 seconds</p>
 163 <p class="p7"><br></p>
 164 </body>
 165 </html>